---
title: API интеграции Astro
i18nReady: true
---
import Since from '~/components/Since.astro'

**Интеграции Astro** добавляют новую функциональность и поведение в ваш проект всего несколькими строками кода.

Эта справочная страница предназначена для тех, кто пишет свои собственные интеграции. Чтобы узнать, как использовать интеграцию в своем проекте, ознакомьтесь с нашим [Руководством по использованию интеграций](/ru/guides/integrations-guide/).

## Примеры

Официальные интеграции Astro могут выступить для вас в качестве примера при создании ваших собственных интеграций.

- **Рендереры:** [`svelte`](/ru/guides/integrations-guide/svelte/), [`react`](/ru/guides/integrations-guide/react/), [`preact`](/ru/guides/integrations-guide/preact/), [`vue`](/ru/guides/integrations-guide/vue/), [`solid`](/ru/guides/integrations-guide/solid-js/)
- **Библиотеки:** [`partytown`](/ru/guides/integrations-guide/partytown/)
- **Функционал:** [`sitemap`](/ru/guides/integrations-guide/sitemap/)

## Краткий справочник по API

```ts
interface AstroIntegration {
  name: string;
  hooks: {
    'astro:config:setup'?: (options: {
      config: AstroConfig;
      command: 'dev' | 'build' | 'preview' | 'sync';
      isRestart: boolean;
      updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
      addRenderer: (renderer: AstroRenderer) => void;
      addWatchFile: (path: URL | string) => void;
      addClientDirective: (directive: ClientDirectiveConfig) => void;
      addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
      addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void;
      injectScript: (stage: InjectedScriptStage, content: string) => void;
      injectRoute: (injectedRoute: InjectedRoute) => void;
      createCodegenDir: () => URL;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:route:setup'?: (options: {
      route: RouteOptions;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:routes:resolved'?: (options: {
      routes: IntegrationResolvedRoute[];
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:config:done'?: (options: {
      config: AstroConfig;
      setAdapter: (adapter: AstroAdapter) => void;
      injectTypes: (injectedType: InjectedType) => URL;
      logger: AstroIntegrationLogger;
      buildOutput: 'static' | 'server';
    }) => void | Promise<void>;
    'astro:server:setup'?: (options: {
      server: vite.ViteDevServer;
      logger: AstroIntegrationLogger;
      toolbar: ReturnType<typeof getToolbarServerCommunicationHelpers>;
      refreshContent?: (options: RefreshContentOptions) => Promise<void>;
    }) => void | Promise<void>;
    'astro:server:start'?: (options: {
      address: AddressInfo;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:server:done'?: (options: {
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:start'?: (options: {
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:setup'?: (options: {
      vite: vite.InlineConfig;
      pages: Map<string, PageBuildData>;
      target: 'client' | 'server';
      updateConfig: (newConfig: vite.InlineConfig) => void;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:ssr'?: (options: {
      manifest: SerializedSSRManifest;
      entryPoints: Map<IntegrationRouteData, URL>;
      middlewareEntryPoint: URL | undefined;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:generated'?: (options: {
      dir: URL;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:done'?: (options: {
      pages: { pathname: string }[];
      dir: URL;
      assets: Map<string, URL[]>;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;

    // ... любые кастомные хуки для интеграций
  };
}
```

## Хуки

Astro предоставляет хуки, которые интеграции могут реализовать для выполнения на определённых этапах жизненного цикла Astro. Хуки Astro определены в интерфейсе `IntegrationHooks`, который является частью глобального пространства имён `Astro`. Каждый хук имеет опцию [`logger`](#astrointegrationlogger), позволяющую использовать логгер Astro для записи логов.

В Astro встроены следующие хуки:

### `astro:config:setup`

**Следующий хук:** [`astro:route:setup`](#astroroutesetup)

**Когда:** При инициализации, перед тем как [Vite](https://vite.dev/config/) или [конфигурация Astro](/ru/reference/configuration-reference/) будут разрешены.

**Зачем:** Для расширения конфигурации проекта. Это включает обновление [конфигурации Astro](/ru/reference/configuration-reference/), применение [плагинов Vite](https://vite.dev/guide/api-plugin.html), добавление рендеров компонентов и внедрение скриптов на страницу.

```ts
'astro:config:setup'?: (options: {
  config: AstroConfig;
  command: 'dev' | 'build' | 'preview' | 'sync';
  isRestart: boolean;
  updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
  addRenderer: (renderer: AstroRenderer) => void;
  addClientDirective: (directive: ClientDirectiveConfig) => void;
  addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
  addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void;
  addWatchFile: (path: URL | string) => void;
  injectScript: (stage: InjectedScriptStage, content: string) => void;
  injectRoute: (injectedRoute: InjectedRoute) => void;
  createCodegenDir: () => URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;
```

#### Опция `config`

<p>

**Тип:** `AstroConfig`
</p>

Доступная только для чтения копия пользовательской [конфигурации Astro](/ru/reference/configuration-reference/). Это разрешается _до_ запуска любых других интеграций. Если вам нужна копия конфигурации после того, как все интеграции завершили обновление своих конфигураций, [см. хук `astro:config:done`](#astroconfigdone).

#### Опция `command`

<p>

**Тип:** `'dev' | 'build' | 'preview' | 'sync'`
</p>

- `dev` — Проект выполняется с помощью `astro dev`
- `build` — Проект выполняется с помощью `astro build`
- `preview` — Проект выполняется с помощью `astro preview`
- `sync` — Проект выполняется с помощью `astro sync`

#### Опция `isRestart`

<p>

**Тип:** `boolean`<br />
<Since v="1.5.0" />
</p>

`false` при запуске сервера разработки, `true` при срабатывании перезагрузки. Полезно для определения, когда эта функция вызывается более одного раза.

#### Опция `updateConfig`

<p>

**Тип:** `(newConfig: DeepPartial<AstroConfig>) => AstroConfig;`
</p>

Функция обратного вызова для обновления предоставленной пользователем [конфигурации Astro](/ru/reference/configuration-reference/). Любая предоставленная вами конфигурация **будет объединена с пользовательской конфигурацией + обновлениями конфигурации других интеграций,** поэтому вы можете не включать ключи!

Например, предположим, что вам нужно добавить в проект пользователя плагин [Vite](https://vite.dev/):

```js
import bananaCSS from '@vitejs/official-banana-css-plugin';

export default {
  name: 'banana-css-integration',
  hooks: {
    'astro:config:setup': ({ updateConfig }) => {
      updateConfig({
        vite: {
          plugins: [bananaCSS()],
        }
      })
    }
  }
}
```

#### Опция `addRenderer`

<p>

**Тип:** `(renderer:` [`AstroRenderer`](https://github.com/withastro/astro/blob/fdd607c5755034edf262e7b275732519328a33b2/packages/astro/src/%40types/astro.ts#L872-L883) `) => void;`<br />
**Примеры:** [`svelte`](https://github.com/withastro/astro/blob/main/packages/integrations/svelte/src/index.ts), [`react`](https://github.com/withastro/astro/blob/main/packages/integrations/react/src/index.ts), [`preact`](https://github.com/withastro/astro/blob/main/packages/integrations/preact/src/index.ts), [`vue`](https://github.com/withastro/astro/blob/main/packages/integrations/vue/src/index.ts), [`solid`](https://github.com/withastro/astro/blob/main/packages/integrations/solid/src/index.ts)
</p>

Функция обратного вызова для добавления рендерера фреймворка компонентов (например, React, Vue, Svelte и т. д.). Вы можете просмотреть примеры и определение типа выше для более продвинутых опций, но вот два основных варианта, о которых стоит знать:

- `clientEntrypoint` - путь к файлу, который выполняется на клиенте при каждом использовании вашего компонента. Это в основном для рендеринга или гидратации вашего компонента с помощью JS.
- `serverEntrypoint` - путь к файлу, который выполняется во время запросов с сервера или статической сборки всякий раз, когда используется ваш компонент. Они должны рендерить компоненты в статическую разметку, с хуками для гидратации, если это применимо. Классическим примером является [обратный вызов `renderToString` от React](https://react.dev/reference/react-dom/server/renderToString).

<p><Since v="5.0.0" /></p>

Функции `clientEntrypoint` и `serverEntrypoint` принимают `URL`.

#### Опция `addWatchFile`

<p>

**Тип:** `(path: URL | string) => void`<br />
<Since v="1.5.0" />
</p>

Если ваша интеграция зависит от какого-то конфигурационного файла, за которым Vite не следит и/или для вступления в силу которого требуется полный перезапуск сервера разработки, добавьте его с помощью `addWatchFile`. Каждый раз, при изменении этого файла, сервер разработки Astro будет перезагружен (вы можете проверить, когда произойдет перезагрузка с помощью `isRestart`).

Пример использования:

```js
// Путь должен быть абсолютным!
addWatchFile('/home/user/.../my-config.json');
addWatchFile(new URL('./tailwind.config.js', config.root));
```

#### Опция `addClientDirective`

<p>

**Тип:** `(directive:` [`ClientDirectiveConfig`](https://github.com/withastro/astro/blob/00327c213f74627ac9ca1dec774efa5bf71e9375/packages/astro/src/%40types/astro.ts#L1872-L1875) `) => void;`<br />
<Since v="2.6.0" />
</p>

Добавляет [пользовательскую клиентскую директиву](/ru/reference/directives-reference/#custom-client-directives) для использования в файлах `.astro`.

Обратите внимание, что точки входа директив поставляются только через esbuild и должны быть небольшими, чтобы не замедлять гидратацию компонентов.

Пример использования:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import clickDirective from './astro-click-directive/register.js'

// https://astro.build/config
export default defineConfig({
  integrations: [
    clickDirective()
  ],
});
```

```js title="astro-click-directive/register.js"
/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "client:click",
  hooks: {
    "astro:config:setup": ({ addClientDirective }) => {
      addClientDirective({
        name: "click",
        entrypoint: "./astro-click-directive/click.js",
      });
    },
  },
});
```

```js title="astro-click-directive/click.js"
/**
 * Гидратация при первом нажатии на окно
 * @type {import('astro').ClientDirective}
 */
export default (load, opts, el) => {
  window.addEventListener('click', async () => {
    const hydrate = await load()
    await hydrate()
  }, { once: true })
}
```

Вы также можете добавить типы для директив в файл определения типов вашей библиотеки:

```ts title="astro-click-directive/index.d.ts"
import 'astro'
declare module 'astro' {
  interface AstroClientDirectives {
    'client:click'?: boolean
  }
}
```

#### Опция `addDevToolbarApp`

<p>

**Тип:** `(entrypoint: DevToolbarAppEntry) => void;`<br />
<Since v="3.4.0" />
</p>

Добавляет [пользовательское приложение для панели разработчика](/ru/reference/dev-toolbar-app-reference/).

Пример использования:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import devToolbarIntegration from './astro-dev-toolbar-app/integration.js'

// https://astro.build/config
export default defineConfig({
  integrations: [
    devToolbarIntegration()
  ],
});
```

```js title="astro-dev-toolbar-app/integration.js"
/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "dev-toolbar-app",
  hooks: {
    "astro:config:setup": ({ addDevToolbarApp }) => {
      addDevToolbarApp({
        entrypoint: "./astro-dev-toolbar-app/plugin.js",
        id: "my-plugin",
        name: "My Plugin"
      });
    },
  },
});
```

```js title="astro-dev-toolbar-app/plugin.js"

/**
 * @type {import('astro').DevToolbarApp}
 */
export default {
  id: "my-plugin",
  name: "My Plugin",
  icon: "<svg>...</svg>",
  init() {
    console.log("I'm a dev toolbar app!")
  },
};
```
#### Опция `addMiddleware`

<p>

**Тип:** `(middleware:` [`AstroIntegrationMiddleware`](https://github.com/withastro/astro/blob/852ac0f75dfca1b2602e9cdbfa0447d9998e2449/packages/astro/src/%40types/astro.ts#L2124-L2127) `) => void;`<br />
<Since v="3.5.0" />
</p>

Добавляет [мидлвар](/ru/guides/middleware/), который будет выполняться при каждом запросе. Принимает модуль `entrypoint`, содержащий мидлвар, и параметр `order`, чтобы указать, должен ли он выполняться до (`pre`) или после (`post`) других мидлваров.

```js title="@my-package/integration.js"
/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "my-middleware-package",
  hooks: {
    "astro:config:setup": ({ addMiddleware }) => {
        addMiddleware({
          entrypoint: '@my-package/middleware',
          order: 'pre'
        });
    },
  },
});
```

Мидлвар определяется в пакете с функцией `onRequest`, как и в случае с пользовательским мидлваром.

```js title="@my-package/middleware.js"
import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  if(context.url.pathname === '/some-test-path') {
    return Response.json({
      ok: true
    });
  }

  return next();
});
```

<p><Since v="5.0.0" /></p>

Функция также принимает `URL` для `entrypoint`:

```js title="@my-package/integration.js" ins={9}
/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "my-middleware-package",
  hooks: {
    "astro:config:setup": ({ addMiddleware }) => {
      addMiddleware({
        entrypoint: new URL('./middleware.js', import.meta.url),
        order: 'pre'
      });
    },
  },
});
```

#### Опция `injectRoute`

<p>

**Тип:** `({ pattern: string; entrypoint: string | URL; prerender?: boolean }) => void;`
</p>

Функция обратного вызова для инъекции маршрутов в проект Astro. Инжектируемые маршруты могут быть [страницами `.astro`](/ru/basics/astro-pages/) или [обработчиками маршрутов `.js` и `.ts`](/ru/guides/endpoints/#эндпойнты-для-статических-файлов).

`injectRoute` принимает объект с `pattern` и `entrypoint`.

- `pattern` — куда маршрут должен быть выведен в браузере, например `/foo/bar`. Шаблон может использовать синтаксис пути к файлу Astro для обозначения динамических маршрутов, например `/foo/[bar]` или `/foo/[...bar]`. Обратите внимание, что расширение файла **не** требуется в `pattern`.
- `entrypoint` — обычный модульный указатель, указывающий на страницу `.astro` или обработчик маршрута `.js`/`.ts`, который обрабатывает маршрут, обозначенный в `pattern`.
- `prerender` — булево значение, которое нужно установить, если Astro не может определить ваш экспорт `prerender`.

##### Пример использования:

```js
injectRoute({
  // Используйте синтаксис шаблонов Astro для динамических маршрутов.
  pattern: '/subfolder/[dynamic]',
  // Используйте синтаксис относительного пути для локального маршрута.
  entrypoint: './src/dynamic-page.astro',
  // Используйте только в том случае, если Astro не может определить ваш экспорт `prerender`
  prerender: false
});
```

Для интеграции, предназначенной для установки в других проектах, используйте имя её пакета для указания точки входа маршрута.
Следующий пример показывает пакет, опубликованный в npm как `@fancy/dashboard`, который добавляет маршрут для панели управления:

```js
injectRoute({
  pattern: '/fancy-dashboard',
  entrypoint: '@fancy/dashboard/dashboard.astro'
});
```

При публикации вашего пакета (в данном случае `@fancy/dashboard`) на npm, вы должны экспортировать `dashboard.astro` в ваш `package.json`:

```json title="package.json" "exports"
{
  "name": "@fancy/dashboard",
  // ...
  "exports": { "./dashboard.astro": "./dashboard.astro" }`
}
```

<p><Since v="5.0.0" /></p>

Функция также принимает `URL` для `entrypoint`:

```js "new URL('./dashboard.astro', import.meta.url)"
injectRoute({
  pattern: '/fancy-dashboard',
  entrypoint: new URL('./dashboard.astro', import.meta.url)
});
```

#### Опция `injectScript`

<p>

**Тип:** `(stage: InjectedScriptStage, content: string) => void;`
</p>

Функция обратного вызова для вставки строки содержимого JavaScript на каждую страницу.

Параметр **`stage`** указывает на то, как должен быть вставлен этот скрипт (`content`). Некоторые этапы позволяют вставлять скрипты без модификации, другие - оптимизировать во время [шага сборки Vite](https://vite.dev/guide/build.html):

- `"head-inline"`:  Вставляется в тег `<script>` в `<head>` каждой страницы. **Не** оптимизирован или разрешен Vite.
- `"before-hydration"`: Импортируется на стороне клиента, перед запуском скрипта гидратации. Оптимизируется и разрешается Vite.
- `"page"`: Аналогично `head-inline`, за исключением того, что импортируемый фрагмент обрабатывается Vite и объединяется с любыми другими тегами `<script>`, определенными внутри компонентов Astro на странице. Скрипт будет загружен с помощью `<script type="module">` в конечный вывод страницы, оптимизирован и разрешен Vite.
- ``page-ssr``: Импортируется как отдельный модуль в метаданных каждого компонента страницы Astro. Поскольку на этом этапе импортируется ваш скрипт, глобальный `Astro` недоступен, и ваш скрипт будет запущен только один раз при первом анализе `import`.

   Основное применение этапа `page-ssr` - это вставка CSS `import` на каждую страницу для оптимизации и разрешения Vite:
    ```js
    injectScript('page-ssr', 'import "global-styles.css";');
    ```

#### `createCodegenDir`

<p>

**Тип:** `() => URL;`<br />
<Since v="5.0.0" />
</p>

Функция, которая создаёт папку `<root>/.astro/integrations/<normalized_integration_name>` и возвращает её путь.

Она позволяет вам иметь выделенную папку, избегая конфликтов с другими интеграциями или самим Astro. Эта директория создаётся при вызове данной функции, поэтому можно безопасно записывать файлы напрямую:

```ts title="my-integration.ts"
import { writeFileSync } from 'node:fs'

const integration = {
  name: 'my-integration',
  hooks: {
    'astro:config:setup': ({ createCodegenDir }) => {
      const codegenDir = createCodegenDir()
      writeFileSync(new URL('cache.json', codegenDir), '{}', 'utf-8')
    }
  }
}
```

### `astro:route:setup`

<p><Since v="4.14.0" /></p>

**Предыдущий хук:** [`astro:config:setup`](#astroconfigsetup)

**Следующий хук:** [`astro:routes:resolved`](#astroroutesresolved)

**Когда:** В `astro build` — перед началом сборки. В `astro dev` — во время построения графа модулей и при каждом изменении файлового маршрута (добавление/удаление/обновление).

**Зачем:** Чтобы задать параметры для маршрута во время сборки или запроса, например, включить [рендеринг на стороне сервера по запросу](/ru/guides/on-demand-rendering/#включение-рендеринга-по-запросу).

```js
'astro:route:setup'?: (options: {
  route: RouteOptions;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;
```

#### Опция `route`

<p>

**Тип:** [`RouteOptions`](https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/types/public/integrations.ts#L14-L27)
</p>

Объект со свойством `component` для идентификации маршрута и следующими дополнительными значениями, позволяющими настроить сгенерированный маршрут: `prerender`.

##### `route.component`

<p>
**Тип:** `string`<br />
<Since v="4.14.0" />
</p>

Свойство `component` указывает точку входа, которая будет отображаться на маршруте. Вы можете получить доступ к этому значению до сборки маршрутов, чтобы настроить рендеринг на стороне сервера по запросу для этой страницы.

##### `route.prerender`

<p>
**Тип:** `boolean`<br />
**По умолчанию:** `undefined`<br />
<Since v="4.14.0" />
</p>

Свойство `prerender` используется для настройки [рендеринга на стороне сервера по запросу](/ru/guides/on-demand-rendering/#включение-рендеринга-по-запросу) для маршрута. Если файл маршрута содержит явное значение `export const prerender`, оно будет использоваться по умолчанию вместо `undefined`.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [setPrerender()],
});

function setPrerender() {
  return {
    name: 'set-prerender',
    hooks: {
      'astro:route:setup': ({ route }) => {
        if (route.component.endsWith('/blog/[slug].astro')) {
          route.prerender = true;
        }
      },
    },
  };
}
```

Если окончательное значение после выполнения всех хуков равно `undefined`, маршрут будет использовать значение по умолчанию для предварительного рендеринга на основе опции [`output`](/ru/reference/configuration-reference/#output): предварительный рендеринг для режима `static` и рендеринг по запросу для режима `server`.

### `astro:routes:resolved`

<p>

<Since v="5.0.0" />
</p>

**Предыдущий хук:** [`astro:route:setup`](#astroroutesetup)

**Следующий хук:** [`astro:config:done`](#astroconfigdone) (только во время настройки)

**Когда:** В `astro dev`, также выполняется при каждом изменении файлового маршрута (добавление/удаление/обновление).

**Зачем:** Для доступа к маршрутам и их метаданным

```js
'astro:routes:resolved'?: (options: {
  routes: IntegrationResolvedRoute[];
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;
```

#### Опция `routes`

<p>

**Тип:** [`IntegrationResolvedRoute[]`](#справка-о-типе-integrationresolvedroute)
</p>

Список всех маршрутов с их связанными метаданными.

Пример использования:

```js title="my-integration.mjs"
const integration = () => {
  return {
    name: 'my-integration',
    hooks: {
      'astro:routes:resolved': ({ routes }) => {
        const projectRoutes = routes.filter(r => r.origin === 'project').map(r => r.pattern)
        
        console.log(projectRoutes)
      },
    }
  }
}
```

### `astro:config:done`

**Предыдущий хук:** [`astro:routes:resolved`](#astroroutesresolved)

**Следующий хук:** [`astro:server:setup`](#astroserversetup) при работе в режиме «dev», или [`astro:build:start`](#astrobuildstart) при «production» сборке.

**Когда:** После того, как конфигурация Astro была разрешена, и другие интеграции выполнили свои хуки `astro:config:setup`.

**Зачем:** Для получения окончательной конфигурации для использования в других хуках.

```js
'astro:config:done'?: (options: {
  config: AstroConfig;
  setAdapter: (adapter: AstroAdapter) => void;
  injectTypes: (injectedType: InjectedType) => URL;
  logger: AstroIntegrationLogger;
  buildOutput: 'static' | 'server';
}) => void | Promise<void>;
```

#### Опция `config`

<p>

**Тип:** `AstroConfig`
</p>

Доступная только для чтения копия предоставленной пользователем [конфигурации Astro](/ru/reference/configuration-reference/). Это разрешается _после_ выполнения других интеграций.

#### Опция `setAdapter()`

<p>

**Тип:** `(adapter: AstroAdapter) => void;`
</p>

Делает интеграцию адаптером. Подробнее в [справочнике по API адаптеров](/ru/reference/adapter-reference/).

#### Опция `injectTypes()`

<p>

**Тип:** `(injectedType: { filename: string; content: string }) => URL`<br />
<Since v="4.14.0" />
</p>

Позволяет внедрять типы в проект пользователя, добавляя новый файл `*.d.ts`.

Свойство `filename` будет использоваться для создания файла по пути `/.astro/integrations/<normalized_integration_name>/<normalized_filename>.d.ts` и должно заканчиваться на `".d.ts"`.

Свойство `content` создаёт содержимое файла и должно быть валидным TypeScript.

Кроме того, `injectTypes()` возвращает URL к нормализованному пути, чтобы вы могли позже перезаписать его содержимое или манипулировать им любым удобным способом.

```js
const path = injectTypes({
  filename: "types.d.ts",
  content: "declare module 'virtual:integration' {}"
})
console.log(path) // URL
```

#### Опция `buildOutput`

<p>

**Тип:** `'static' | 'server'`<br />
<Since v="5.0.0" />
</p>

Позволяет адаптировать логику вашей интеграции в зависимости от вывода проекта пользователя.

### `astro:server:setup`

**Предыдущий хук:** [`astro:config:done`](#astroconfigdone)

**Следующий хук:** [`astro:server:start`](#astroserverstart)

**Когда:**  Сразу после создания сервера Vite в режиме «dev», но перед событием `listen()`. [См. API createServer Vite](https://vite.dev/guide/api-javascript.html#createserver) для получения дополнительной информации.

**Зачем:** Для обновления параметров сервера Vite и мидлвара, или включения поддержки обновления слоя контента.

```js
'astro:server:setup'?: (options: {
  server: vite.ViteDevServer;
  logger: AstroIntegrationLogger;
  toolbar: ReturnType<typeof getToolbarServerCommunicationHelpers>;
  refreshContent: (options: {
    loaders?: Array<string>;
    context?: Record<string, any>;
  }) => Promise<void>;
}) => void | Promise<void>;
```

#### Опция `server`

<p>

**Тип:** [`ViteDevServer`](https://vite.dev/guide/api-javascript.html#vitedevserver)
</p>

Изменяемый экземпляр сервера Vite, используемый в режиме «dev». Например, это [используется нашей интеграцией Partytown](/ru/guides/integrations-guide/partytown/) для вставки сервера Partytown в качестве мидлвара:

```js
export default {
  name: 'partytown',
  hooks: {
    'astro:server:setup': ({ server }) => {
      server.middlewares.use(
        function middleware(req, res, next) {
          // обработка запросов
        }
      );
    }
  }
}
```

#### Опция `toolbar`

<p>

**Тип:** `ReturnType<typeof getToolbarServerCommunicationHelpers>`<br />
<Since v="4.7.0" />
</p>

Объект, предоставляющий функции обратного вызова для взаимодействия с [панелью разработчика](/ru/reference/dev-toolbar-app-reference/):

##### `on()`

<p>

**Тип:** `<T>(event: string, callback: (data: T) => void) => void`<br />
</p>

Функция, которая принимает имя события в качестве первого аргумента и функцию обратного вызова в качестве второго аргумента. Это позволяет вам получать сообщения от приложения панели разработчика с данными, связанными с этим событием.

##### `onAppInitialized()`

<p>

**Тип:** `(appId: string, callback: (data: Record<string, never>) => void) => void`<br />
</p>

Функция, вызываемая при инициализации приложения панели разработчика. Первый аргумент — это идентификатор инициализированного приложения. Второй аргумент — функция обратного вызова, которая выполняется при инициализации приложения.

##### `onAppToggled()`

<p>

**Тип:** `(appId: string, callback: (data: { state: boolean; }) => void) => void`<br />
</p>

Функция, вызываемая при включении или выключении приложения панели разработчика. Первый аргумент — это идентификатор приложения, которое было переключено. Второй аргумент — функция обратного вызова, предоставляющая состояние для выполнения при переключении приложения.

##### `send()`

<p>

**Тип:** `<T>(event: string, payload: T) => void`<br />
</p>

Функция, отправляющая сообщение в панель разработчика, которое может прослушиваться приложением. Она принимает имя события в качестве первого аргумента и полезную нагрузку в качестве второго аргумента — это могут быть любые сериализуемые данные.

#### `refreshContent()` option

<p>

**Тип:** `(options: { loaders?: Array<string>; context?: Record<string, any>; }) => Promise<void>`<br />
<Since v="5.0.0" />
</p>

Функция, позволяющая интеграциям инициировать обновление слоя контента во время работы `astro dev`. Например, её можно использовать для регистрации конечной точки вебхука в режиме разработки или для открытия сокета к CMS, чтобы отслеживать изменения.

По умолчанию `refreshContent` обновляет все коллекции. Вы можете дополнительно передать свойство `loaders` — массив имён загрузчиков. Если оно указано, обновятся только коллекции, использующие эти загрузчики. Например, интеграция с CMS может использовать это свойство для обновления только своих коллекций.

Также можно передать объект `context` в загрузчики. Это позволяет передавать произвольные данные, такие как тело вебхука или событие из вебсокета.

```ts title=my-integration.ts {19-22}
{
  name: 'my-integration',
  hooks: {
    'astro:server:setup': async ({ server, refreshContent }) => {
      // Регистрируем конечную точку вебхука для сервера разработки
      server.middlewares.use('/_refresh', async (req, res) => {
        if(req.method !== 'POST') {
          res.statusCode = 405
          res.end('Метод не разрешён');
          return
        }
        let body = '';
        req.on('data', chunk => {
          body += chunk.toString();
        });
        req.on('end', async () => {
          try {
            const webhookBody = JSON.parse(body);
            await refreshContent({
              context: { webhookBody },
              loaders: ['my-loader']
            });
            res.writeHead(200, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ message: 'Контент успешно обновлён' }));
          } catch (error) {
            res.writeHead(500, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ error: 'Не удалось обновить контент: ' + error.message }));
          }
        });
      });
    }
  }
}
```

Загрузчик может затем получить доступ к свойству `refreshContextData`, чтобы получить тело вебхука. Подробнее см. в описании свойства [`refreshContextData`](/ru/reference/content-loader-reference/#refreshcontextdata).

### `astro:server:start`

**Предыдущий хук:** [`astro:server:setup`](#astroserversetup)

**Следующий хук:** [`astro:server:done`](#astroserverdone)

**Когда:** Сразу после срабатывания события `listen()` сервера.

**Зачем:** Для перехвата сетевых запросов по указанному адресу. Если вы намерены использовать этот адрес для мидлвара, рассмотрите возможность использования `astro:server:setup` вместо этого.

```js
'astro:server:start'?: (options: {
  address: AddressInfo;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;
```

#### Опция `address`

<p>

**Тип:** [`AddressInfo`](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules__types_node_net_d_._net_.addressinfo.html)
</p>

Адрес, семейство и номер порта, предоставленные [модулем Net Node.js](https://nodejs.org/api/net.html).

### `astro:server:done`

**Предыдущий хук:** [`astro:server:start`](#astroserverstart)

**Когда:** Сразу после закрытия сервера разработки.

**Зачем:** Для выполнения любых событий очистки, которые могут быть запущены во время хуков `astro:server:setup` или `astro:server:start`.

```js
'astro:server:done'?: (options: {
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;
```

### `astro:build:start`

**Предыдущий хук:** [`astro:config:done`](#astroconfigdone)

**Следующий хук:** [`astro:build:setup`](#astrobuildsetup)

**Когда:** После события `astro:config:done`, но перед запуском сборки для продакшена.

**Зачем:** Для настройки любых глобальных объектов или клиентов, необходимых во время продакшен-сборки. Это также может расширить параметры конфигурации сборки в [API адаптера](/ru/reference/adapter-reference/).

```js
'astro:build:start'?: (options: {
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;
```

### `astro:build:setup`

**Предыдущий хук:** [`astro:build:start`](#astrobuildstart)

**Следующий хук:** [`astro:build:ssr`](#astrobuildssr)

**Когда:** После хука `astro:build:start`, запускается непосредственно перед сборкой.

**Зачем:** На этом этапе конфигурация Vite для сборки полностью сконструирована, это ваш последний шанс её изменить. Это может быть полезно, например, для перезаписи некоторых значений по умолчанию. Если вы не уверены, следует ли использовать этот хук или `astro:build:start`, используйте вместо этого `astro:build:start`.

```js
'astro:build:setup'?: (options: {
  vite: vite.InlineConfig;
  pages: Map<string, PageBuildData>;
  target: 'client' | 'server';
  updateConfig: (newConfig: vite.InlineConfig) => void;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

```

#### Опция `vite`

<p>

**Тип:** [`InlineConfig`](https://vite.dev/guide/api-javascript.html#inlineconfig)
</p>

Объект, позволяющий получить доступ к конфигурации Vite, используемой при сборке.

Это может быть полезно, если вам нужно получить доступ к параметрам конфигурации в вашей интеграции:

```js
export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ vite }) => {
      const { publicDir, root } = vite;
    },
  }
}
```

#### Опция `pages`

<p>

**Тип:** <code>Map\<string, <a href="https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/core/build/types.ts#L17-L23">PageBuildData</a>\></code>
</p>

`Map`, содержащий список страниц в качестве ключей и их данные сборки в качестве значений.

Это можно использовать для выполнения действия, если маршрут соответствует определённому критерию:

```js
export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ pages }) => {
      pages.forEach((data) => {
        if (data.route.pattern.test("/blog")) {
          console.log(data.route.type);
        }
      });
    },
  }
}
```

#### Опция `target`

<p>

**Тип:** `'client' | 'server'`
</p>

Сборка разделена на две фазы: `client` и `server`. Эта опция позволяет определить текущую фазу сборки.

Её можно использовать для выполнения действия только в определённой фазе:

```js
export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ target }) => {
      if (target === "server") {
        // делаем что-нибудь в фазе сервера
      }
    },
  }
}
```

#### Опция `updateConfig()`

<p>

**Тип:** <code>(newConfig: <a href="https://vite.dev/guide/api-javascript.html#inlineconfig">InlineConfig</a>) => void</code>
</p>

Функция обратного вызова для обновления параметров [Vite](https://vite.dev/), используемых при сборке. Любая предоставленная вами конфигурация **будет объединена с конфигурацией пользователя и обновлениями других интеграций**, поэтому вы можете свободно опускать ключи!

Например, это можно использовать для добавления плагина в проект пользователя:

```js
import awesomeCssPlugin from 'awesome-css-vite-plugin';

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ updateConfig }) => {
      updateConfig({
        plugins: [awesomeCssPlugin()],
      })
    }
  }
}
```

### `astro:build:ssr`

**Предыдущий хук:** [`astro:build:setup`](#astrobuildsetup)

**Следующий хук:** [`astro:build:generated`](#astrobuildgenerated)

**Когда:** После завершения продакшен-сборки с SSR.

**Зачем:** Для доступа к SSR-манифесту и карте созданных точек входа. Это полезно при создании пользовательских SSR-сборок в плагинах или интеграциях.
- `entryPoints` сопоставляет маршрут страницы с физическим файлом, созданным после сборки;
- `middlewareEntryPoint` - путь файловой системы к файлу мидлвара;

```js
'astro:build:ssr'?: (options: {
  manifest: SerializedSSRManifest;
  entryPoints: Map<IntegrationRouteData, URL>;
  middlewareEntryPoint: URL | undefined;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;
```

#### Опция `manifest`

<p>

**Тип:** [`SerializedSSRManifest`](https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/core/app/types.ts#L91-L109)
</p>

Позволяет создать пользовательскую сборку, получая доступ к SSR-манифесту.

```js
export default {
  name: 'my-integration',
  hooks: {
    'astro:build:ssr': ({ manifest }) => {
      const { i18n } = manifest;
      if (i18n?.strategy === "domains-prefix-always") {
        // что-то делаем
      }
    },
  },
}
```

#### Опция `entryPoints`

<p>

**Тип:** <code>Map\<<a href="#справка-о-типе-integrationroutedata">IntegrationRouteData</a>, URL\></code><br />
<Since v="2.7.0" />
</p>

`Map` созданных точек входа, где ключом являются данные `IntegrationRouteData`, а значением — URL физического файла.

```js
export default {
  name: 'my-integration',
  hooks: {
    'astro:build:ssr': ({ entryPoints }) => {
      entryPoints.forEach((url) => {
        console.log(url.href);
      });
    },
  },
}
```

#### Опция `middlewareEntryPoint`

<p>

**Тип:** `URL | undefined`<br />
<Since v="2.8.0" />
</p>

Предоставляет путь к файлу [мидлвара](/ru/guides/middleware/).

```js
export default {
  name: 'my-integration',
  hooks: {
    'astro:build:ssr': ({ middlewareEntryPoint }) => {
      if (middlewareEntryPoint) {
        // выполняем какие-нибудь операции, если существует мидлвар
      }
    },
  },
}
```

### `astro:build:generated`

<p>

<Since v="1.3.0" />
</p>

**Предыдущий хук:** [`astro:build:ssr`](#astrobuildssr)

**Следующий хук:** [`astro:build:done`](#astrobuilddone)

**Когда:** После завершения статической продакшен-сборки, генерирующей маршруты и ресурсы.

**Зачем:** Для доступа к сгенерированным маршрутам и ресурсам **до** очистки артефактов сборки. Это очень редкий случай использования. Мы рекомендуем использовать [`astro:build:done`](#astrobuilddone), если вам действительно нужен доступ к сгенерированным файлам перед очисткой.

```js
'astro:build:generated'?: (options: {
  dir: URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;
```

#### Опция `dir`

<p>

**Тип:** [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)
</p>

URL-путь к директории вывода сборки. Обратите внимание, что если вам нужна валидная абсолютная строка пути, следует использовать встроенную в Node утилиту [`fileURLToPath`](https://nodejs.org/api/url.html#urlfileurltopathurl-options).

```js
import { fileURLToPath } from 'node:url';

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:generated': ({ dir }) => {
      const outFile = fileURLToPath(new URL('./my-integration.json', dir));
    }
  }
}
```

### `astro:build:done`

**Предыдущий хук:** [`astro:build:generated`](#astrobuildgenerated)

**Когда:** После завершения продакшен-сборки (SSG или SSR).

**Зачем:**  Чтобы получить доступ к сгенерированным маршрутам и ресурсам для расширения (например, скопировать содержимое в сгенерированную директорию `/assets`). Если вы планируете преобразовывать сгенерированные ресурсы, мы рекомендуем использовать [API плагинов Vite](https://vite.dev/guide/api-plugin.html) и [настройку через `astro:config:setup`](#опция-updateconfig) вместо этого.

```js
'astro:build:done'?: (options: {
  pages: { pathname: string }[];
  dir: URL;
  /** @deprecated Используйте карту `assets`` и новый хук `astro:routes:resolved` */
  routes: IntegrationRouteData[];
  assets: Map<string, URL[]>;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;
```

#### Опция `dir`

<p>

**Тип:** [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)
</p>

URL-путь к выходному каталогу сборки. Обратите внимание, что если вам нужна валидная строка абсолютного пути, вам следует использовать встроенную в Node утилиту [`fileURLToPath`](https://nodejs.org/api/url.html#urlfileurltopathurl).

```js
import { writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

export default function myIntegration() {
  return {
    hooks: {
      'astro:build:done': async ({ dir }) => {
        const metadata = await getIntegrationMetadata();
        // Используем `fileURLToPath`, чтобы получить валидную абсолютную строку пути, совместимую с разными платформами
        const outFile = fileURLToPath(new URL('./my-integration.json', dir));
        await writeFile(outFile, JSON.stringify(metadata));
      }
    }
  }
}
```

#### Опция `routes`

:::caution
Это свойство устарело начиная с v5.0. Ознакомьтесь с [руководством по миграции](/ru/guides/upgrade-to/v5/#устаревшее-routes-в-хуке-astrobuilddone-api-интеграций).
:::

<p>

**Тип:** [`IntegrationRouteData[]`](#справка-о-типе-integrationroutedata)
</p>

Список всех сгенерированных маршрутов вместе с их метаданными.

Вы можете ссылаться на полный тип `IntegrationRouteData` ниже, но наиболее часто используемые свойства:

- `component` — путь к входному файлу относительно корня проекта
- `pathname` — URL выходного файла (не определен для маршрутов с параметрами `[dynamic]` и `[...spread]`)

#### Опция `assets`

<p>

**Тип:** `Map<string, URL[]>`<br />
<Since v="5.0.0" />
</p>

Содержит URL-адреса путей к выходным файлам, сгруппированные по свойству `pattern` типа [`IntegrationResolvedRoute`](#справка-о-типе-integrationresolvedroute).

#### Опция `pages`

<p>

**Тип:** `{ pathname: string }[]`
</p>

Список всех сгенерированных страниц. Это объект с одним свойством.

- `pathname` — окончательный путь страницы.

### Пользовательские хуки

Пользовательские хуки можно добавлять в интеграции, расширяя интерфейс `IntegrationHooks` с помощью [глобального расширения](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#global-augmentation).

```ts
declare global {
  namespace Astro {
    export interface IntegrationHook {
      'your:hook': (params: YourHookParameters) => Promise<void>
    }
  }
}
```

Astro резервирует префикс `astro:` для будущих встроенных хуков. Пожалуйста, выберите другой префикс при именовании вашего пользовательского хука.

## Справочник по типам интеграций

### `AstroIntegrationLogger`

Экземпляр логгера Astro, полезный для записи логов. Этот логгер использует тот же [уровень логирования](/ru/reference/cli-reference/#--verbose), что и настроенный через CLI.


**Доступные методы** для записи в терминал:
- `logger.info("Сообщение")`;
- `logger.warn("Сообщение")`;
- `logger.error("Сообщение")`;
- `logger.debug("Сообщение")`;

Все сообщения предваряются меткой, значение которой совпадает с именем интеграции.

```ts title="integration.ts" {8}
import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
  return {
    name: "astro-format",
    hooks: {
      "astro:build:done": ({ logger }) => {
        // делаем что-нибудь
        logger.info("Интеграция готова.");
      }
    }
  }
}
```

Пример выше запишет сообщение, включающее предоставленное `info`-сообщение:

```shell
[astro-format] Integration ready.
```

Чтобы записать сообщения с другой меткой, используйте метод `.fork`, чтобы указать альтернативу значению по умолчанию `name`:

```ts title="integration.ts" ".fork"
import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
  return {
    name: "astro-format",
    hooks: {
      "astro:config:done": ({ logger }) => {
        // делаем что-нибудь
        logger.info("Интеграция готова.");
      },
      "astro:build:done": ({ logger }) => {
        const buildLogger = logger.fork("astro-format/build");
        // делаем что-нибудь
        buildLogger.info("Сборка завершена.")
      }
    }
  }
}
```

Пример выше будет создавать логи с `[astro-format]` по умолчанию и `[astro-format/build]`, когда это указано:

```shell
[astro-format] Интеграция готова.
[astro-format/build] Сборка завершена.
```

### `HookParameters`

Вы можете получить тип аргументов хука, передав имя хука в утилиту типа `HookParameters`. В следующем примере аргумент `options` функции типизирован в соответствии с параметрами хука `astro:config:setup`:

```ts /HookParameters(?:<.+>)?/
import type { HookParameters } from 'astro';

function mySetup(options: HookParameters<'astro:config:setup'>) {
  options.updateConfig({ /* ... */ });
}
```

### Справка о типе `IntegrationResolvedRoute`

```ts
interface IntegrationResolvedRoute {
  pattern: RouteData['route'];
  patternRegex: RouteData['pattern'];
  entrypoint: RouteData['component'];
  isPrerendered: RouteData['prerender'];
  redirectRoute?: IntegrationResolvedRoute;
  generate: (data?: any) => string;
  params: string[];
  pathname?: string;
  segments: RoutePart[][];
  type: RouteType;
  redirect?: RedirectConfig;
  origin: 'internal' | 'external' | 'project';
}
```

#### `pattern`

<p>

**Тип:** `string`
</p>

Позволяет определить тип маршрута на основе его пути. Вот несколько примеров путей, связанных с их шаблоном:
* `src/pages/index.astro` будет `/`
* `src/pages/blog/[...slug].astro` будет `/blog/[...slug]`
* `src/pages/site/[blog]/[...slug].astro` будет `/site/[blog]/[...slug]`

#### `patternRegex`

<p>

**Тип:** `RegExp`
</p>

Позволяет получить доступ к регулярному выражению, используемому для сопоставления входного URL с запрошенным маршрутом.

Например, для пути `[fruit]/about.astro` регулярное выражение будет `/^\/([^/]+?)\/about\/?$/`. Использование `pattern.test("banana/about")` вернёт `true`.

#### `entrypoint`

<p>

**Тип:** `string`
</p>

Путь URL исходного компонента.

#### `isPrerendered`

<p>

**Тип:** `boolean`
</p>

Определяет, использует ли маршрут [рендеринг по запросу](/ru/guides/on-demand-rendering/). Значение будет `true` для проектов, настроенных следующим образом:
* `output: 'static'`, когда маршрут не экспортирует `const prerender = true`
* `output: 'server'`, когда маршрут экспортирует `const prerender = false`

#### `redirectRoute`

<p>

**Тип:** `IntegrationResolvedRoute | undefined`
</p>

Когда значение `IntegrationResolvedRoute.type` равно `redirect`, значение будет `IntegrationResolvedRoute`, на который нужно перенаправить. В противном случае значение будет неопределённым.

#### `generate()`

<p>

**Тип:** `(data?: any) => string`
</p>

Функция, которая предоставляет необязательные параметры маршрута, интерполирует их с шаблоном маршрута и возвращает имя пути маршрута.

Например, для маршрута, такого как `/blog/[...id].astro`, функция `generate` может вернуть:

```js
console.log(generate({ id: 'presentation' })) // выведет `/blog/presentation`
```

#### `params`

<p>

**Тип:** `string[]`
</p>

Позволяет получить доступ к `params` маршрута. Например, когда проект использует следующие [динамические маршруты](/ru/guides/routing/#dynamic-routes) `/pages/[lang]/[...slug].astro`, значение будет `['lang', '...slug']`.

#### `pathname`

<p>

**Тип:** `string | undefined`
</p>

Для обычных маршрутов значение будет представлять собой путь URL, по которому будет обслуживаться этот маршрут. Когда проект использует [динамические маршруты](/ru/guides/routing/#dynamic-routes) (т. е. `[dynamic]` или `[...spread]`), путь будет неопределённым.

#### `segments`

<p>

**Тип:** <code><a href="https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/types/public/internal.ts#L154-L158">RoutePart</a>[][]</code>
</p>

Позволяет получить доступ к [`params`](#params) маршрута с дополнительной метаинформацией. Каждый объект содержит следующие свойства:
* `content`: имя `param`,
* `dynamic`: является ли маршрут динамическим или нет,
* `spread`: использует ли динамический маршрут синтаксис распространения или нет.

Например, следующий маршрут `/pages/[blog]/[...slug].astro` выведет сегменты:

```js
[
  [ { content: 'pages', dynamic: false, spread: false } ],
  [ { content: 'blog', dynamic: true, spread: false } ],
  [ { content: '...slug', dynamic: true, spread: true } ]
]
```

#### `type`

<p>

**Тип:** `RouteType`
</p>

Позволяет определить тип маршрута. Возможные значения:
* `page`: маршрут, который находится в файловой системе, обычно это компонент Astro
* `endpoint`: маршрут, который находится в файловой системе, обычно это JS-файл, который предоставляет методы эндпойнтов
* `redirect`: маршрут, который указывает на другой маршрут, находящийся в файловой системе
* `fallback`: маршрут, который не существует в файловой системе и который необходимо обрабатывать другими средствами, обычно с помощью мидлваров

#### `redirect`

<p>

**Тип:** <code><a href="https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/types/public/config.ts#L39-L44">RedirectConfig</a> | undefined</code>
</p>

Позволяет получить доступ к маршруту, на который нужно перенаправить. Это может быть строка или объект, содержащий информацию о статусном коде и его назначении.

#### `origin`

<p>

**Тип:** `'internal' | 'external' | 'project'`
</p>

Определяет, поступает ли маршрут из ядра Astro (`internal`), интеграции (`external`) или проекта пользователя (`project`).

### Справка о типе `IntegrationRouteData`

:::caution
Этот тип устарел с версии v5.0. Используйте вместо него [`IntegrationResolvedRoute`](#справка-о-типе-integrationresolvedroute).
:::

Упрощенная версия `RouteData`, которая используется в интеграциях.

```ts
interface IntegrationRouteData {
  type: RouteType;
  component: string;
  pathname?: string;
  pattern: RegExp;
  params: string[];
  segments: { content: string; dynamic: boolean; spread: boolean; }[][];
  generate: (data?: any) => string;
  prerender: boolean;
  distURL?: URL[];
  redirect?: RedirectConfig;
  redirectRoute?: IntegrationRouteData;
}
```

#### `type`

<p>

**Тип:** `RouteType`
</p>

Позволяет определить тип маршрута. Значение может быть:
- `page`: маршрут, который находится в файловой системе, обычно это компонент Astro
- `endpoint`: маршрут, который находится в файловой системе, обычно это JS-файл, который предоставляет методы эндпойнтов
- `redirect`: маршрут, который указывает на другой маршрут, находящийся в файловой системе
- `fallback`: маршрут, который не существует в файловой системе и который необходимо обрабатывать другими средствами, обычно с помощью мидлваров

#### `component`

<p>

**Тип:** `string`
</p>

Позволяет получить доступ к пути URL исходного компонента.

#### `pathname`

<p>

**Тип:** `string | undefined`
</p>

Для обычных маршрутов значение будет представлять собой путь URL, по которому будет обслуживаться этот маршрут. Когда проект использует [динамические маршруты](/ru/guides/routing/#dynamic-routes) (т. е. `[dynamic]` или `[...spread]`), путь будет неопределённым.

#### `pattern`

<p>

**Тип:** `RegExp`
</p>

Позволяет получить доступ к регулярному выражению, используемому для сопоставления входного URL с запрашиваемым маршрутом.

Например, для пути `[fruit]/about.astro` регулярное выражение будет `/^\/([^/]+?)\/about\/?$/`. Использование `pattern.test("banana/about")` вернет `true`.

#### `params`

<p>

**Тип:** `string[]`
</p>

Позволяет получить доступ к `params` маршрута. Например, когда проект использует следующие [динамические маршруты](/ru/guides/routing/#dynamic-routes) `/pages/[lang]/[...slug].astro`, значение будет `['lang', '...slug']`.

#### `segments`

<p>

**Тип:** `{ content: string; dynamic: boolean; spread: boolean; }[][]`
</p>

Позволяет получить доступ к [`params`](#params-1) маршрута с дополнительной метаинформацией. Каждый объект содержит следующие свойства:
* `content`: `param`,
* `dynamic`: является ли маршрут динамическим или нет,
* `spread`: использует ли динамический маршрут синтаксис распространения или нет.

Например, следующий маршрут `/pages/[lang]/index.astro` выведет сегменты `[[ { content: 'lang', dynamic: true, spread: false } ]]`.

#### `generate()`

<p>

**Тип:** `(data?: any) => string`
</p>

Функция, которая предоставляет необязательные параметры маршрута, интерполирует их с шаблоном маршрута и возвращает имя пути маршрута.

Например, для маршрута, такого как `/blog/[...id].astro`, функция `generate` может вернуть:

```js
console.log(generate({ id: 'presentation' })) // выведет `/blog/presentation` 
```

#### `prerender`

<p>

**Тип:** `boolean`
</p>

Определяет, является ли маршрут предварительно отрендеренным или нет.

#### `distURL`

<p>

**Тип:** `URL[] | undefined`
</p>

Пути физических файлов, создаваемых этим маршрутом. Когда маршрут **не является** предварительно отрендеренным, значение будет либо `undefined`, либо пустым массивом.

#### `redirect`

<p>

**Тип:** <code><a href="https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/types/public/config.ts#L39-L44">RedirectConfig</a> | undefined</code>
</p>

Позволяет получить доступ к маршруту, на который нужно перенаправить. Это может быть строка или объект, содержащий информацию о статусном коде и его назначении.

#### `redirectRoute`

<p>

**Тип:** `IntegrationRouteData | undefined`
</p>

Когда значение `RouteData.type` равно `redirect`, значение будет содержать `IntegrationRouteData` маршрута, на который нужно перенаправить. В противном случае значение будет неопределенным.

## Разрешаем установку с помощью `astro add`

[Команда `astro add`](/ru/reference/cli-reference/#astro-add) позволяет пользователям легко добавлять интеграции и адаптеры в свой проект. Если вы хотите, чтобы _ваша_ интеграция могла быть установлена с помощью этого инструмента, **добавьте `astro-integration` в поле `keywords` в вашем `package.json`**:

```json
{
  "name": "example",
  "keywords": ["astro-integration"],
}
```

После того как вы [опубликуете свою интеграцию в npm](https://docs.npmjs.com/cli/v8/commands/npm-publish), выполнение команды `astro add example` установит ваш пакет с любыми зависимостями, указанными в вашем `package.json`. Это также применит вашу интеграцию к `astro.config.*` пользователя следующим образом:

```js ins={3,6}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import example from 'example';

export default defineConfig({
  integrations: [example()],
})
```

:::caution
Это предполагает, что определение вашей интеграции 1) является `default` экспортом и 2) является функцией. Убедитесь, что это так, прежде чем добавлять ключевое слово `astro-integration`!
:::

## Порядок интеграций

Все интеграции выполняются в порядке, в котором они настроены. Например, для массива `[react(), svelte()]` в `astro.config.*` пользователя, `react` будет выполняться перед `svelte`.

Ваша интеграция должна, в идеале, работать в любом порядке. Если это невозможно, мы рекомендуем задокументировать, что ваша интеграция должна быть первой или последней в массиве конфигурации `integrations` пользователя.

## Объединение интеграций в пресеты

Интеграция также может быть написана как коллекция нескольких, более мелких интеграций. Мы называем эти коллекции **пресетами**. Вместо создания фабричной функции, которая возвращает один объект интеграции, пресет возвращает _массив_ объектов интеграции. Это полезно для создания сложных функций из нескольких интеграций.

```js
integrations: [
  // Пример, где examplePreset() возвращает: [integrationOne, integrationTwo, ...etc]
  examplePreset()
]
```

## Ресурсы сообщества

- [Создание ваших собственных интеграций Astro](https://www.freecodecamp.org/news/how-to-use-the-astro-ui-framework/#chapter-8-build-your-own-astro-integrations-1) - Эммануэль Оханс на FreeCodeCamp
- [Шаблон интеграции Astro](https://github.com/florian-lefebvre/astro-integration-template) - Флориан Лефебр на GitHub
